home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kbookmarkmanager.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  12.1 KB  |  368 lines
  1. //  -*- c-basic-offset:4; indent-tabs-mode:nil -*-
  2. // vim: set ts=4 sts=4 sw=4 et:
  3. /* This file is part of the KDE libraries
  4.    Copyright (C) 2000 David Faure <faure@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License version 2 as published by the Free Software Foundation.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20. #ifndef __kbookmarkmanager_h
  21. #define __kbookmarkmanager_h
  22.  
  23. #include <qstring.h>
  24. #include <qstringlist.h>
  25. #include <qobject.h>
  26. #include <qdom.h>
  27. #include <dcopobject.h>
  28. #include "kbookmark.h"
  29. #include "kbookmarknotifier.h"
  30.  
  31. /**
  32.  * This class implements the reading/writing of bookmarks in XML.
  33.  * The bookmarks file is read and written using the XBEL standard
  34.  * (http://pyxml.sourceforge.net/topics/xbel/)
  35.  *
  36.  * A sample file looks like this :
  37.  * \code
  38.  * <xbel>
  39.  *   <bookmark href="http://developer.kde.org"><title>Developer Web Site</title></bookmark>
  40.  *   <folder folded="no">
  41.  *     <title>Title of this folder</title>
  42.  *     <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
  43.  *     <folder toolbar="yes">
  44.  *       <title>My own bookmarks</title>
  45.  *       <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
  46.  *       <separator/>
  47.  *       <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
  48.  *     </folder>
  49.  *   </folder>
  50.  * </xbel>
  51.  * \endcode
  52.  */
  53. class KIO_EXPORT KBookmarkManager : public QObject, public DCOPObject
  54. {
  55.     Q_OBJECT
  56.     K_DCOP
  57. protected:
  58.     /**
  59.      * Creates a bookmark manager with a path to the bookmarks.  By
  60.      * default, it will use the KDE standard dirs to find and create the
  61.      * correct location.  If you are using your own app-specific
  62.      * bookmarks directory, you must instantiate this class with your
  63.      * own path <em>before</em> KBookmarkManager::managerForFile() is ever
  64.      * called.
  65.      *
  66.      * @param bookmarksFile full path to the bookmarks file,
  67.      * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
  68.      *
  69.      * @param bImportDesktopFiles if true, and if the bookmarksFile
  70.      * doesn't already exist, import bookmarks from desktop files
  71.      */
  72.     KBookmarkManager( const QString & bookmarksFile, bool bImportDesktopFiles = true );
  73.  
  74.     /**
  75.      * @since 3.2
  76.      */
  77.     KBookmarkManager();
  78.  
  79. public:
  80.     /**
  81.      * Destructor
  82.      */
  83.     ~KBookmarkManager();
  84.  
  85.     /**
  86.      * Set the update flag. Defaults to true. TODO - check
  87.      * @param update if true then KBookmarkManager will listen to DCOP update requests.
  88.      */
  89.     void setUpdate( bool update );
  90.  
  91.     /**
  92.      * Save the bookmarks to the default konqueror XML file on disk.
  93.      * You should use emitChanged() instead of this function, it saves
  94.      * and notifies everyone that the file has changed.
  95.      * @param toolbarCache iff true save a cache of the toolbar folder, too
  96.      * @return true if saving was successful
  97.      */
  98.     bool save( bool toolbarCache = true ) const;
  99.  
  100.     /**
  101.      * Save the bookmarks to the given XML file on disk.
  102.      * @param filename full path to the desired bookmarks file location
  103.      * @param toolbarCache iff true save a cache of the toolbar folder, too
  104.      * @return true if saving was successful
  105.      */
  106.     bool saveAs( const QString & filename, bool toolbarCache = true ) const;
  107.  
  108.     /**
  109.      * Update access time stamps for a given url.
  110.      * @param url the viewed url
  111.      * @param emitSignal iff true emit KBookmarkNotifier signal
  112.      * @since 3.2
  113.      * @return true if any metadata was modified (bookmarks file is not saved automatically)
  114.      */
  115.     bool updateAccessMetadata( const QString &url, bool emitSignal = true );
  116.  
  117.     /*
  118.      * NB. currently *unimplemented*
  119.      *
  120.      * Update favicon url for a given url.
  121.      * @param url the viewed url
  122.      * @param faviconurl the favicion url
  123.      * @emitSignal iff true emit KBookmarkNotifier signal
  124.      * @since 3.3
  125.      */
  126.     void updateFavicon( const QString &url, const QString &faviconurl, bool emitSignal = true );
  127.  
  128.     /**
  129.      * This will return the path that this manager is using to read
  130.      * the bookmarks.
  131.      * @internal
  132.      * @return the path containing the bookmarks
  133.      */
  134.     QString path() { return m_bookmarksFile; }
  135.  
  136.     /**
  137.      * This will return the root bookmark.  It is used to iterate
  138.      * through the bookmarks manually.  It is mostly used internally.
  139.      *
  140.      * @return the root (top-level) bookmark
  141.      */
  142.     KBookmarkGroup root() const;
  143.  
  144.     /**
  145.      * This returns the root of the toolbar menu.
  146.      * In the XML, this is the group with the attribute TOOLBAR=1
  147.      *
  148.      * @return the toolbar group
  149.      */
  150.     KBookmarkGroup toolbar();
  151.  
  152.     /**
  153.      * @return the bookmark designated by @p address
  154.      * @param address the address belonging to the bookmark you're looking for
  155.      * @param tolerate when true tries to find the most tolerable bookmark position
  156.      * @see KBookmark::address
  157.      */
  158.     KBookmark findByAddress( const QString & address, bool tolerate = false );
  159.  
  160.     /**
  161.      * Saves the bookmark file and notifies everyone.
  162.      * @param group the parent of all changed bookmarks
  163.      */
  164.     void emitChanged( KBookmarkGroup & group );
  165.  
  166.     void emitConfigChanged();
  167.  
  168.     /**
  169.      * @return true if the NS bookmarks should be dynamically shown
  170.      *         in the toplevel kactionmenu
  171.      * @deprecated
  172.      */
  173.     bool showNSBookmarks() const;
  174.  
  175.     /**
  176.      * Shows an extra menu for NS bookmarks. Set this to false, if you don't
  177.      * want this.
  178.      */
  179.     void setShowNSBookmarks( bool show );
  180.  
  181.     /**
  182.      * Set options with which slotEditBookmarks called keditbookmarks
  183.      * this can be used to change the appearance of the keditbookmarks
  184.      * in order to provide a slightly differing outer shell depending
  185.      * on the bookmarks file / app which calls it.
  186.      * @param caption the --caption string, for instance "Konsole"
  187.      * @param browser iff false display no browser specific
  188.      *            menu items in keditbookmarks :: --nobrowser
  189.      * @since 3.2
  190.      */
  191.     void setEditorOptions( const QString& caption, bool browser );
  192.  
  193.     /**
  194.      * This static function will return an instance of the
  195.      * KBookmarkManager, responsible for the given @p bookmarksFile.
  196.      * If you do not instantiate this class either
  197.      * natively or in a derived class, then it will return an object
  198.      * with the default behaviors.  If you wish to use different
  199.      * behaviors, you <em>must</em> derive your own class and
  200.      * instantiate it before this method is ever called.
  201.      *
  202.      * @param bookmarksFile full path to the bookmarks file,
  203.      * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
  204.      *
  205.      * @param bImportDesktopFiles if true, and if the bookmarksFile
  206.      * doesn't already exist, import bookmarks from desktop files
  207.      * @return a pointer to an instance of the KBookmarkManager.
  208.      */
  209.     static KBookmarkManager* managerForFile( const QString& bookmarksFile,
  210.                                    bool bImportDesktopFiles = true );
  211.  
  212.  
  213.     static KBookmarkManager* createTempManager();
  214.  
  215.     /**
  216.      * Returns a pointer to the users main bookmark collection.
  217.      * @since 3.2
  218.      */
  219.     static KBookmarkManager* userBookmarksManager();
  220.     
  221.     /**
  222.      * Returns the path to the user's main bookmark collection file.
  223.      * @since 3.5.5
  224.      */
  225.     static QString userBookmarksFile();
  226.  
  227.     /**
  228.      * @internal
  229.      */
  230.     const QDomDocument & internalDocument() const;
  231.  
  232.     /**
  233.      * Access to bookmark notifier, for emitting signals.
  234.      * We need this object to exist in one instance only, so we could
  235.      * connectDCOP to it by name.
  236.      */
  237.     KBookmarkNotifier& notifier() { return m_notifier; }
  238.  
  239.     /**
  240.      * @since 3.2
  241.      */
  242.     KBookmarkGroup addBookmarkDialog( const QString & _url, const QString & _title,
  243.                                       const QString & _parentBookmarkAddress = QString::null );
  244.  
  245. public slots:
  246.     void slotEditBookmarks();
  247.     void slotEditBookmarksAtAddress( const QString& address );
  248.  
  249. public:
  250. k_dcop:
  251.     /**
  252.      * Reparse the whole bookmarks file and notify about the change
  253.      * (Called by the bookmark editor)
  254.      */
  255.     ASYNC notifyCompleteChange( QString caller );
  256.  
  257.     /**
  258.      * Emit the changed signal for the group whose address is given
  259.      * @see KBookmark::address()
  260.      * Called by the instance of konqueror that saved the file after
  261.      * a small change (new bookmark or new folder).
  262.      */
  263.     ASYNC notifyChanged( QString groupAddress );
  264.  
  265.     ASYNC notifyConfigChanged();
  266.  
  267. signals:
  268.     /**
  269.      * Signals that the group (or any of its children) with the address 
  270.      * @p groupAddress (e.g. "/4/5")
  271.      * has been modified by the caller @p caller.
  272.      */
  273.     void changed( const QString & groupAddress, const QString & caller );
  274.  
  275. protected:
  276.     // consts added to avoid a copy-and-paste of internalDocument
  277.     void parse() const;
  278.     void importDesktopFiles();
  279.     static void convertToXBEL( QDomElement & group );
  280.     static void convertAttribute( QDomElement elem, const QString & oldName, const QString & newName );
  281.  
  282. private:
  283.     KBookmarkNotifier m_notifier;
  284.     QString m_bookmarksFile;
  285.     mutable QDomDocument m_doc;
  286.     mutable QDomDocument m_toolbarDoc;
  287.     mutable bool m_docIsLoaded;
  288.     bool m_update;
  289.     static QPtrList<KBookmarkManager>* s_pSelf;
  290.     bool m_showNSBookmarks;
  291.  
  292. private:
  293.     class KBookmarkManagerPrivate* dptr() const;
  294. };
  295.  
  296. /**
  297.  * The KBookmarkMenu and KBookmarkBar classes gives the user
  298.  * the ability to either edit bookmarks or add their own.  In the
  299.  * first case, the app may want to open the bookmark in a special way.
  300.  * In the second case, the app <em>must</em> supply the name and the
  301.  * URL for the bookmark.
  302.  *
  303.  * This class gives the app this callback-like ability.
  304.  *
  305.  * If your app does not give the user the ability to add bookmarks and
  306.  * you don't mind using the default bookmark editor to edit your
  307.  * bookmarks, then you don't need to overload this class at all.
  308.  * Rather, just use something like:
  309.  *
  310.  * <CODE>
  311.  * bookmarks = new KBookmarkMenu(new KBookmarkOwner(), ...)
  312.  * </CODE>
  313.  *
  314.  * If you wish to use your own editor or allow the user to add
  315.  * bookmarks, you must overload this class.
  316.  */
  317. class KIO_EXPORT KBookmarkOwner
  318. {
  319. public:
  320.   /**
  321.    * This function is called if the user selects a bookmark.  It will
  322.    * open up the bookmark in a default fashion unless you override it.
  323.    */
  324.   virtual void openBookmarkURL(const QString& _url);
  325.  
  326.   /**
  327.    * This function is called whenever the user wants to add the
  328.    * current page to the bookmarks list.  The title will become the
  329.    * "name" of the bookmark.  You must overload this function if you
  330.    * wish to give your users the ability to add bookmarks.
  331.    *
  332.    * @return the title of the current page.
  333.    */
  334.   virtual QString currentTitle() const { return QString::null; }
  335.  
  336.   /**
  337.    * This function is called whenever the user wants to add the
  338.    * current page to the bookmarks list.  The URL will become the URL
  339.    * of the bookmark.  You must overload this function if you wish to
  340.    * give your users the ability to add bookmarks.
  341.    *
  342.    * @return the URL of the current page.
  343.    */
  344.   virtual QString currentURL() const { return QString::null; }
  345.  
  346. protected:
  347.   virtual void virtual_hook( int id, void* data );
  348. };
  349.  
  350. /**
  351.  * @since 3.2
  352.  */
  353. class KIO_EXPORT KExtendedBookmarkOwner : public QObject, virtual public KBookmarkOwner
  354. {
  355.     Q_OBJECT
  356. public:
  357.     typedef QValueList<QPair<QString,QString> > QStringPairList;
  358. public slots:
  359.     void fillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list ) { emit signalFillBookmarksList( list ); };
  360. signals:
  361.     void signalFillBookmarksList( KExtendedBookmarkOwner::QStringPairList & list );
  362. private:
  363.     class KExtendedBookmarkOwnerPrivate;
  364.     KExtendedBookmarkOwnerPrivate *d;
  365. };
  366.  
  367. #endif
  368.